home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d7 / litecom6.arc / PROTO.DOC < prev    next >
Text File  |  1991-08-29  |  39KB  |  1,787 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                                         Chapter 1
  14.  
  15.                              GETTING STARTED WITH PROTOCOLS
  16.  
  17.  
  18.             1.1  INTRODUCTION
  19.  
  20.  
  21.             The LiteComm protocol engines are designed to simplify the task
  22.             of moving large quantities of information over communications
  23.             lines. Since communications lines are notoriously subject to
  24.             noise, each of the engines imposes a protocol or set of rules
  25.             that help insure the integrity of the information. Since the
  26.             rules that are used are necessarily complex, the engines remove
  27.             many of the concerns that normally confront programmers.
  28.  
  29.             You can see the application of many of the concepts that we
  30.             discuss in the sample program QBTTL. QBTTL is distributed, in
  31.             both source and executable forms, as part of the LiteComm
  32.             package. You should review QBTTL carefully for additional
  33.             understanding.
  34.  
  35.  
  36.             1.2  BASIC ENGINE INTERFACE
  37.  
  38.  
  39.             Several protocol engines are included as part of LiteComm. They
  40.             include:
  41.  
  42.                 o  XModem
  43.  
  44.                 o  XModem-1K
  45.  
  46.                 o  Windowed XModem
  47.  
  48.                 o  YModem
  49.  
  50.                 o  ZModem
  51.  
  52.             Each of these protocol has its own strengths and weaknesses. And
  53.             each has very different rules. Yet, we have attempted to make the
  54.             programming for each as common as possible, whenever practical.
  55.  
  56.             To use any of the protocol engines, you must follow a series of
  57.             steps. Unless indicated otherwise, these steps are required
  58.             regardless of the protocol that is being employed.
  59.  
  60.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  61.                                Protocol Engines
  62.  
  63.  
  64.  
  65.        1.2.1  PROTOCOL INITIALIZATION
  66.  
  67.        The initialization phase for the protocol engines requires two
  68.        essential steps, plus several optional steps depending upon your
  69.        applications needs.
  70.  
  71.           1.  Open a communication port using the comm_opn function. You
  72.               must specify buffer sizes at least as large as the size of
  73.               a protocol transfer block. For XModem and Windowed XModem,
  74.               the buffers must be at least 128 bytes. For XModem-1K,
  75.               YModem, and ZModem, the buffers must be at least 1024 (1K)
  76.               bytes. In general, we use 2K buffers for most
  77.               applications, assuming that there is adequate memory to
  78.               support this buffer size.
  79.  
  80.           2.  Set the port parameters to NO PARITY, 8 DATA BITS. This
  81.               can be done when the port is originally opened, or by
  82.               using the lc_setup function.
  83.  
  84.           3.  Disable software (XON-XOFF) flow control, if it has been
  85.               activated. In general, XModem, XModem-1K, and YModem
  86.               cannot tolerate software flow control. Windowed XModem and
  87.               ZModem are designed to work with software flow control.
  88.  
  89.           4.  Allocate a protocol control block (pcb) for the port,
  90.               using the lcp_alloc function. The lcp_alloc function
  91.               builds the essential control structures that are used by
  92.               the protocol engines. Once allocated, a pcb may be reused
  93.               as often as required without using the lcp_free function.
  94.  
  95.           5.  Initialize the pcb by calling the lcp_setproto function.
  96.               This function establishes the starting values for the
  97.               requested protocol. The lcp_setproto function should be
  98.               called before initiating each protocol session.
  99.  
  100.           6.  Optionally install an abort function that can cause the
  101.               engine to abort a transfer session, based upon an event
  102.               you define. One such event might be the recognition of a
  103.               keystroke, such as ESC, to permit the user to abort
  104.               protocol operations.
  105.  
  106.           7.  Optionally install a status function that can process
  107.               status messages being issued by the engine. Your
  108.               application might use this function to display appropriate
  109.               messages to the user.
  110.  
  111.           8.  Optionally use the lcp_setsignal macro to inform the
  112.               protocol engines that you to monitor that signal. If you
  113.               use this facility, the protocol engines will abort
  114.               operation if the signal is not present.
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.                                     Page 2
  123.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  124.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  125.                                     Protocol Engines
  126.  
  127.  
  128.  
  129.             1.2.2  DATA TRANSFER
  130.  
  131.             The method employed to actually transfer data is dependent upon
  132.             the protocol in use. The XModem, XModem-1K, and Windowed XModem
  133.             protocols place the burden on the programmer to read data from
  134.             and write data to the disk. See QBTTL for examples of this
  135.             interface.
  136.  
  137.             Due to the added complexity, both the YModem and ZModem engines
  138.             handle all aspects of file transfers. You simply provide a list
  139.             of files to send, or a path to which to store files and the
  140.             engines do the rest.
  141.  
  142.             1.2.3  PROTOCOL SHUTDOWN
  143.  
  144.             Shutting down a protocol engine simply requires that you use the
  145.             lcp_free function to release the memory reserved by lcp_alloc. Do
  146.             not attempt to use the compiler's free function to do this. All
  147.             reserved memory will not be released by free.
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.                                          Page 3
  187.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  188.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  189.                                Protocol Engines
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.                                     Page 4
  251.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  252.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  253.                                     Protocol Engines
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.                                         Chapter 2
  264.  
  265.                                  INITIALIZATION DETAILS
  266.  
  267.  
  268.             2.1  THE MANDATORY FUNCTIONS
  269.  
  270.  
  271.             The two essential initialization functions are lcp_alloc and
  272.             lcp_setproto. Use of both functions is absolutely essential for
  273.             successful engine operation.
  274.  
  275.             2.1.1  LCP_ALLOC
  276.  
  277.             Function lcp_alloc sets aside memory for a protocol control block
  278.             or pcb. A pcb is defined the lcproto.h header file as a type
  279.             definition or typedef of PROTO. Once the pcb is built, a transfer
  280.             buffer is allocated for use by the protocol engines, and is
  281.             associated with the pcb.
  282.  
  283.             We take pains to inform you of the details for two reasons:
  284.  
  285.                 o  To convince you that it is to your advantage to use the
  286.                    match lcp_free function to release the pcb.
  287.  
  288.                 o  To help you understand that multiple pcb's will use
  289.                    significant amounts of system memory.  For example, the
  290.                    transfer buffer is about 2K bytes long, regardless of the
  291.                    protocol that is being used.
  292.  
  293.                 o  While you may access the values contained in the pcb, your
  294.                    program should never attempt to alter the values found
  295.                    there, unless you are absolutely certain about what you
  296.                    are doing.
  297.  
  298.             Due to a design decision, you need only construct a pcb once
  299.             during the program. The pcb is reusable from transfer session to
  300.             session. It is not necessary to use lcp_free between transfer
  301.             sessions.
  302.  
  303.             2.1.2  LCP_SETPROTO
  304.  
  305.             The lcp_setproto function actually does the initialization work.
  306.             When you call lcp_setproto, the function initializes the target
  307.             pcb with the correct values for the selected protocol. Since
  308.             lcp_setproto does do initialization, you must use lcp_setproto
  309.             before each transfer session. Failure to observe this restriction
  310.             may result in failure of the transfer with unexpected results.
  311.  
  312.  
  313.  
  314.                                          Page 5
  315.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  316.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  317.                                Protocol Engines
  318.  
  319.  
  320.  
  321.        2.2  THE OPTIONAL STEPS
  322.  
  323.  
  324.        2.2.1  ABORT FUNCTION
  325.  
  326.        Each of the protocol engines periodically calls an abort
  327.        function. By default, this is a do-nothing function that simply
  328.        satisfies the linker. But if you wish, you may install an abort
  329.        handler of your own. The function must be of type ABORTFUNC, as
  330.        defined in lcproto.h.
  331.  
  332.        The reason for the abort function is to give  you a hook into the
  333.        engines. The abort function takes no arguments. To inform the
  334.        engine that you wish to abort a transfer in progress, your abort
  335.        function should return a nonzero value. To let the transfer
  336.        continue, your function should return a value of zero.
  337.  
  338.        If you intend to use an abort function please keep this in mind.
  339.        All of the protocols are time-sensitive to a greater or lesser
  340.        degree. Your abort function should execute as quickly as
  341.        possible, with a minimum of delay.
  342.  
  343.        If you want to use an abort function, simply assign your function
  344.        to lcp_abort. Lcp_abort is defined within lcproto, the protocol
  345.        common code, as shown below:
  346.  
  347.                       lcp_abort = my_abort;
  348.  
  349.        before the transfer session is started.
  350.  
  351.        2.2.2  STATUS FUNCTION
  352.  
  353.        Like the abort function, the protocol engines provide a second
  354.        hook for monitoring progress and status information. By default,
  355.        LiteComm engines call a dummy status routine of type STATFUNC. If
  356.        you use a status function of your own, it must be of that type.
  357.  
  358.        A STATFUNC takes three arguments, a message code, an integer
  359.        value, and a void pointer that must be cast, depending upon the
  360.        type of information that is being reported.  The meaning of the
  361.        integer and pointer values must be considered in the context of
  362.        the message code.
  363.  
  364.        To help keep things clear, we have developed two tables, below,
  365.        for each of the major protocol groups, the XModem group, and the
  366.        ZModem group.
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.                                     Page 6
  379.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  380.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  381.                                     Protocol Engines
  382.  
  383.  
  384.  
  385.                              Table 2.1: XModem Status Codes
  386.  
  387.                 CODE       INTEGER VALUE   POINTER TYPE      MEANING
  388.  
  389.             CAN            0                 PROTO *     Cancel received
  390.             DUPSEQ         rec number        PROTO *     Duplicate block
  391.             EOT            0                 PROTO *     End of File
  392.             FATAL          rec number        PROTO *     Other fatal error
  393.             RETRIES        rec number        PROTO *     Too many tries
  394.             SUCCESS        count of chars    PROTO *     Block transferred OK
  395.             TOUT           0                 PROTO *     Timeout
  396.             WAITACK        retrys            PROTO *     Waiting for ack
  397.             WAITBLK        retrys            PROTO *     Waiting for block
  398.             WAITFNB        0                 PROTO *     Waiting, file name
  399.             WAITHDSK       retrys            PROTO *     Waiting, handshake
  400.             WAITSOH        retrys            PROTO *     Waiting for SOH
  401.             XBADFILE       index             NULL        Can't find file
  402.             XDISKERR       count of chars    PROTO *     Read/Write Error
  403.             XGOTFILE       0                 TELINK *    Received file name
  404.  
  405.  
  406.                              Table 2.2: ZModem Status Codes
  407.  
  408.                 CODE       INTEGER VALUE   POINTER TYPE      MEANING
  409.  
  410.             ZBADFILE       index             NULL          Can't find file
  411.             ZBADHDR        0                 PROTO *       Bad header
  412.             ZBADPOS        0                 PROTO *       Position error
  413.             ZDISKERR       count of chars    PROTO *       Read/Write error
  414.             ZFCREAT        0                 TELINK *      Can't create file
  415.             ZFOPEN         0                 TELINK *      Error opening file
  416.             ZGOTFILE       0                 TELINK *      Received file name
  417.             ZINITTO        0                 PROTO *       Init timeout
  418.             ZNOCAR         0                 PROTO *       Loss of carrier
  419.             ZPKTLEN        packet length     PROTO *       Packet too long
  420.             ZRECOVER       0                 TELINK *      Attempted recovery
  421.             ZSEEKERR       0                 PROTO *       File seek error
  422.             ZTIMER         0                 PROTO *       Timeout Error
  423.             ZXFRCAN        0                 PROTO *       Transfer cancelled
  424.  
  425.             Of the integer values that are passed, the value specified as
  426.             "index" requires added explanation. The YModem and ZModem send
  427.             functions expect a list of file names to be sent. The index that
  428.             is passed is the number of filename in that list, with zero (0)
  429.             being the first file in the list.
  430.  
  431.             As with the abort function, to implement you own status function,
  432.             assign your function to lcp_status as:
  433.  
  434.                                 lcp_status = my_status.
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.                                          Page 7
  443.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  444.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  445.                                Protocol Engines
  446.  
  447.  
  448.  
  449.        2.2.3  SIGNAL MONITORING
  450.  
  451.        One of the nastiest problems to deal with in protocol transfers
  452.        is recognizing that the other system is no longer connected.
  453.        Under most protocols, the session will eventually abort due to
  454.        timeout errors. But, depending upon the protocol, a significant
  455.        amount of time may elapse before this happens.  In LiteComm's
  456.        implementation of XModem, for example, up to 100 seconds may
  457.        elapse.
  458.  
  459.        As a result, LiteComm engines will optionally monitor one of
  460.        several modem status signals, if you so choose. To cause LiteComm
  461.        to monitor a signal, use the lcp_setsignal macro, as follows:
  462.  
  463.                       lcp_setsignal(p, DCD);
  464.  
  465.        In this example, LiteComm will monitor the DCD (carrier detect)
  466.        signal. If carrier is lost, then LiteComm will cancel the
  467.        transfer.
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.                                     Page 8
  507.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  508.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  509.                                     Protocol Engines
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.                                         Chapter 3
  520.  
  521.                                    FUNCTION REFERENCE
  522.  
  523.  
  524.             3.1  INTRODUCTION
  525.  
  526.  
  527.             In the information that follows, we describe, in detail, the
  528.             functions used with the protocol engines. We assume that you are
  529.             familiar with standard C notation.
  530.  
  531.             In your use of the functions, we encourage your use of symbolic
  532.             constants whenever possible. Failure to do so make your code
  533.             incompatible with future versions of LiteComm.
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.                                         lcp_alloc
  541.  
  542.  
  543.             SUMMARY
  544.  
  545.  
  546.                  #include litecomm.h
  547.                  #include lcproto.h
  548.  
  549.                  PROTO *lcp_alloc(unsigned port);
  550.  
  551.  
  552.             DESCRIPTION
  553.  
  554.  
  555.             Allocates and builds a protocol control block (pcb) of type
  556.             PROTO. Allocates memory for a transfer buffer to be associated
  557.             with the pcb. This function must be used before any other
  558.             protocol-related function. The pcb should only be released with
  559.             the lcp_free function.
  560.  
  561.  
  562.             EXAMPLE
  563.  
  564.  
  565.                  PROTO *pcb;
  566.  
  567.  
  568.  
  569.  
  570.                                          Page 9
  571.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  572.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  573.                                Protocol Engines
  574.  
  575.  
  576.  
  577.             if ((pcb = lcp_alloc(port)) == NULL)
  578.             {
  579.                  puts("Insufficient Memory");
  580.                  return;
  581.             }
  582.  
  583.  
  584.        RETURN VALUES
  585.  
  586.  
  587.        The function returns a pointer to the new pcb, or NULL if there
  588.        is not enough heap space to build the pcb and related buffer.
  589.  
  590.  
  591.        SEE ALSO
  592.  
  593.  
  594.             lcp_free
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.                                     Page 10
  635.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  636.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  637.                                     Protocol Engines
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.                                         lcp_free
  648.  
  649.  
  650.             SUMMARY
  651.  
  652.  
  653.                  #include "litecomm.h"
  654.                  #include "lcproto.h"
  655.  
  656.                  void lcp_free(PROTO *pcb);
  657.  
  658.  
  659.             DESCRIPTION
  660.  
  661.  
  662.             Releases the memory allocated by lcp_alloc. Lcp_free cannot
  663.             determine whether the referenced pcb pointer is valid. Attempting
  664.             to free an improperly allocated pcb will result in unpredictable
  665.             results.
  666.  
  667.  
  668.             RETURN VALUES
  669.  
  670.  
  671.             This function returns no values.
  672.  
  673.  
  674.             SEE ALSO
  675.  
  676.  
  677.                  lcp_alloc
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.                                          Page 11
  699.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  700.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  701.                                Protocol Engines
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.                                  lcp_setproto
  712.  
  713.  
  714.        SUMMARY
  715.  
  716.  
  717.             #include "litecomm.h"
  718.             #include "lcproto.h"
  719.  
  720.             lcp_setproto(PROTO *pcb, unsigned char protocol, int
  721.                  usecrc);
  722.  
  723.  
  724.        DESCRIPTION
  725.  
  726.  
  727.        Initializes the target pcb for a new transfer session using the
  728.        specified protocol. Valid values for protocol are XMODEM,
  729.        XMODEM1K, WXMODEM, YMODEM, and ZMODEM.
  730.  
  731.        The usecrc parameter only has meaning for XMODEM and XMODEM1K.
  732.        For these protocols, a nonzero value tells LiteComm to receive
  733.        using the more effective CRC. A zero value tells LiteComm to
  734.        receive using Checksums.
  735.  
  736.        The function does not check to see if the pcb pointer is valid.
  737.        Use of an invalid pcb pointer will cause unexpected errors.
  738.  
  739.  
  740.        EXAMPLE
  741.  
  742.  
  743.             PROTO *pcb;
  744.  
  745.             if (lcp_setproto(pcb, XMODEM1K, 1) == -1)
  746.                  puts("Error setting the protocol");
  747.  
  748.  
  749.        RETURN VALUES
  750.  
  751.  
  752.        The function returns a value of zero if no errors were
  753.        encountered. A return value of -1 indicates that the protocol
  754.        specified is invalid.
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.                                     Page 12
  763.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  764.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  765.                                     Protocol Engines
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.                                       lcp_setsignal
  776.  
  777.  
  778.             SUMMARY
  779.  
  780.  
  781.                  #include "litecomm.h"
  782.                  #include "lcproto.h"
  783.  
  784.                  lcp_setsignal(PROTO *p, unsigned char signal);
  785.  
  786.  
  787.             DESCRIPTION
  788.  
  789.  
  790.             This is not a true function, but is rather a macro. The
  791.             specification for signal should be one of the following: DCD,
  792.             CTS, DSR. Only one signal at a time may be specified; they may
  793.             not be OR'ed to monitor multiple signals.
  794.  
  795.             Since this is not a true function, no error checking will be
  796.             performed.
  797.  
  798.  
  799.             RETURN VALUES
  800.  
  801.  
  802.             No values are returned.
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.                                          Page 13
  827.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  828.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  829.                                Protocol Engines
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.                                    lcpxmsnd
  840.  
  841.  
  842.        SUMMARY
  843.  
  844.  
  845.             #include "litecomm.h"
  846.             #include "lcproto.h"
  847.             #include "lcpxm.h"
  848.  
  849.             int lcpxmsnd(PROTO *pcb);
  850.  
  851.  
  852.        DESCRIPTION
  853.  
  854.  
  855.        Send a block of data using either XMODEM or XMODEM-1K protocol,
  856.        as determined by the lcp_setproto function. The function
  857.        automatically performs initial handshaking with the target
  858.        system. Upon each call, the contents of pcb->buff, the transfer
  859.        buffer, are sent to the target system.  It is the programmers
  860.        responsibility to load the transfer buffer with the appropriate
  861.        amount of data, 128 bytes for XModem, 1024 bytes for XModem-1K,
  862.        before calling lcpxmsnd.
  863.  
  864.        This function is called repeatedly until all data has been
  865.        transferred, or until the transfer is aborted or cancelled. Once
  866.        all data has been sent, the transfer is ended by calling the
  867.        function lcxteot.
  868.  
  869.  
  870.        EXAMPLE
  871.  
  872.  
  873.        See QBTTL.
  874.  
  875.  
  876.        RETURN VALUES
  877.  
  878.  
  879.        The significant return values, and there related actions are
  880.        shown below:
  881.  
  882.            o  SUCCESS - Block was sent successfully. Send the next block
  883.               or EOT.
  884.  
  885.            o  CAN - The receiving system has requested that the transfer
  886.               be cancelled. No further action is necessary.
  887.  
  888.  
  889.  
  890.                                     Page 14
  891.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  892.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  893.                                     Protocol Engines
  894.  
  895.  
  896.  
  897.                 o  RETRIES - The block could not be sent successfully after
  898.                    10 attempts. No further action is possible.
  899.  
  900.                 o  All Others - A fatal condition was detected. No further
  901.                    action is possible.
  902.  
  903.  
  904.             SEE ALSO
  905.  
  906.  
  907.                  lcp_setproto, lcxteot
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.                                          Page 15
  955.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  956.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  957.                                Protocol Engines
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.                                    lcpxmrec
  968.  
  969.  
  970.        SUMMARY
  971.  
  972.  
  973.             #include "litecomm.h"
  974.             #include "lcproto.h"
  975.             #include "lcpxm.h"
  976.  
  977.             int lcpxmrec(PROTO *pcb);
  978.  
  979.  
  980.        DESCRIPTION
  981.  
  982.  
  983.        Receive a block of data using XMODEM or XMODEM-1K. All initial
  984.        handshaking with the sending system is done automatically. If a
  985.        block is successfully received, it will be in the transfer buffer
  986.        at pcb->buff.  The length of the received block will be in
  987.        pcb->rbsize.  It is the responsibility of the programmer to write
  988.        the contents of the transfer buffer to disk.
  989.  
  990.        The function is called repeatedly until the transfer is
  991.        cancelled, aborted, or completed.
  992.  
  993.  
  994.        EXAMPLE
  995.  
  996.  
  997.        See QBTTL.
  998.  
  999.  
  1000.        RETURN VALUES
  1001.  
  1002.  
  1003.        The significant return values, and there related actions are
  1004.        shown below:
  1005.  
  1006.            o  SUCCESS - Block was received successfully. Write the block
  1007.               to disk and attempt to receive the next block.
  1008.  
  1009.            o  DUPSEQ - The block received was a duplicate of the
  1010.               previous block. Ignore the block and attempt to receive
  1011.               the next block.
  1012.  
  1013.            o  CAN - The receiving system has requested that the transfer
  1014.               be cancelled. No further action is necessary.
  1015.  
  1016.  
  1017.  
  1018.                                     Page 16
  1019.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1020.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  1021.                                     Protocol Engines
  1022.  
  1023.  
  1024.  
  1025.                 o  EOT - There is no more data to receive, end of file has
  1026.                    been reached.  No further action is necessary.
  1027.  
  1028.                 o  TOUT - While waiting for a block from the sending system,
  1029.                    too much time elapsed, approximately 100 seconds. No
  1030.                    further action is possible.
  1031.  
  1032.                 o  RETRIES - The block could not be received successfully
  1033.                    after 10 attempts. No further action is possible.
  1034.  
  1035.                 o  All Others - A fatal condition was detected. No further
  1036.                    action is possible.
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.                                          Page 17
  1083.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1084.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  1085.                                Protocol Engines
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.                                    lcpwxsnd
  1096.  
  1097.  
  1098.        SUMMARY
  1099.  
  1100.  
  1101.             #include "litecomm.h"
  1102.             #include "lcproto.h"
  1103.             #include "lcpxm.h"
  1104.  
  1105.             int lcpwxsnd(PROTO *pcb, int *nrec);
  1106.  
  1107.  
  1108.        DESCRIPTION
  1109.  
  1110.  
  1111.        Send a block of data using the Windowed XModem protocol.
  1112.  
  1113.        This function is called repeatedly to transfer data to the
  1114.        receiving system. It is the responsibility of the programmer to
  1115.        fill the transfer buffer located at pcb->buff with 128 bytes of
  1116.        data before each call. In addition, for each block of data, the
  1117.        contents of the variable nrec must be set to zero.
  1118.  
  1119.        If a block is transferred successfully, the function is called
  1120.        again to send the next block of data. When all data has been
  1121.        sent, the function is called with nrec set to a value of -1 to
  1122.        signify end of file.
  1123.  
  1124.  
  1125.        EXAMPLE
  1126.  
  1127.  
  1128.        See QBTTL.
  1129.  
  1130.  
  1131.        RETURN VALUES
  1132.  
  1133.  
  1134.        The significant return values, and there related actions are
  1135.        shown below. Please note that, under some circumstances, the
  1136.        value of nrec has importance.
  1137.  
  1138.            o  SUCCESS - Block was sent successfully. If nrec has a value
  1139.               of -1, the receiving system has acknowledged End Of File,
  1140.               and no further action is needed. Otherwise, send the next
  1141.               block or signal end of file by setting nrec to -1.
  1142.  
  1143.  
  1144.  
  1145.  
  1146.                                     Page 18
  1147.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1148.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  1149.                                     Protocol Engines
  1150.  
  1151.  
  1152.  
  1153.                 o  CAN - The receiving system has requested that the transfer
  1154.                    be cancelled. No further action is necessary.
  1155.  
  1156.                 o  RETRIES - The block could not be sent successfully after
  1157.                    10 attempts. No further action is possible.
  1158.  
  1159.                 o  RESEND - The receiving system has requested that you
  1160.                    retransmit date beginning with the block specified by
  1161.                    nrec. You must reposition the file to the specified block
  1162.                    and begin sending from that point.  The location of the
  1163.                    start of the block is calculated by multiplying the value
  1164.                    of nrec by 128.  The result should always be a long
  1165.                    integer.
  1166.  
  1167.                 o  All Others - A fatal condition was detected. No further
  1168.                    action is possible.
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.                                          Page 19
  1211.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1212.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  1213.                                Protocol Engines
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.                                    lcpwxrec
  1224.  
  1225.  
  1226.        SUMMARY
  1227.  
  1228.  
  1229.             #include "litecomm.h"
  1230.             #include "lcproto.h"
  1231.             #include "lcpxm.h"
  1232.  
  1233.             int lcpwxrec(PROTO *pcb, int *nrec);
  1234.  
  1235.  
  1236.        DESCRIPTION
  1237.  
  1238.  
  1239.        Receive a block of data using the Windowed XModem protocol.All
  1240.        initial handshaking with the sending system is done
  1241.        automatically. If a block is successfully received, it will be in
  1242.        the transfer buffer at pcb->buff.  The length of the received
  1243.        block will always be 128 bytes.  It is the responsibility of the
  1244.        programmer to write the contents of the transfer buffer to disk.
  1245.  
  1246.        The function is called repeatedly until the transfer is
  1247.        cancelled, aborted, or completed.
  1248.  
  1249.  
  1250.        EXAMPLE
  1251.  
  1252.  
  1253.        See QBTTL.
  1254.  
  1255.  
  1256.        RETURN VALUES
  1257.  
  1258.  
  1259.        The significant return values, and there related actions are
  1260.        shown below. Please note that, under some circumstances, the
  1261.        value of nrec has importance.
  1262.  
  1263.            o  SUCCESS - Block was received successfully. Write the block
  1264.               to disk and attempt to receive the next block.
  1265.  
  1266.            o  DUPSEQ - The block received was a duplicate of the
  1267.               previous block. Ignore the block and attempt to receive
  1268.               the next block.
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.                                     Page 20
  1275.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1276.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  1277.                                     Protocol Engines
  1278.  
  1279.  
  1280.  
  1281.                 o  CAN - The receiving system has requested that the transfer
  1282.                    be cancelled. No further action is necessary.
  1283.  
  1284.                 o  EOT - There is no more data to receive, end of file has
  1285.                    been reached.  No further action is necessary.
  1286.  
  1287.                 o  TOUT - While waiting for a block from the sending system,
  1288.                    too much time elapsed, approximately 100 seconds. No
  1289.                    further action is possible.
  1290.  
  1291.                 o  RETRIES - The block could not be received successfully
  1292.                    after 10 attempts. No further action is possible.
  1293.  
  1294.                 o  All Others - A fatal condition was detected. No further
  1295.                    action is possible.
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.                                          Page 21
  1339.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1340.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  1341.                                Protocol Engines
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.                                    lcym_send
  1352.  
  1353.  
  1354.        SUMMARY
  1355.  
  1356.  
  1357.             #include "litecomm.h"
  1358.             #include "lcproto.h"
  1359.             #include "lcpxm.h"
  1360.  
  1361.             int lcym_send(PROTO *pcb, char **filelist);
  1362.  
  1363.  
  1364.        DESCRIPTION
  1365.  
  1366.  
  1367.        Send one or more files using YModem protocol.
  1368.  
  1369.        Due to the complexities of batch transfers, the programmer must
  1370.        create a list of file names to be transferred. QBTTL shows one
  1371.        approach to building the list. This is not necessarily the best
  1372.        approach. The file list must end with a zero length file name.
  1373.  
  1374.        Once called, all files will be sent to the receiving system,
  1375.        unless the transfer is canceled or aborted.
  1376.  
  1377.        MSC USERS NOTE: The files to be transferred should be either in
  1378.        the default directory, or in a directory specified in the PATH
  1379.        environment variable.
  1380.  
  1381.  
  1382.        EXAMPLE
  1383.  
  1384.  
  1385.        See QBTTL.
  1386.  
  1387.  
  1388.        RETURN VALUES
  1389.  
  1390.  
  1391.        This function returns no values.
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.                                     Page 22
  1403.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1404.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  1405.                                     Protocol Engines
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.                                         lcym_recv
  1416.  
  1417.  
  1418.             SUMMARY
  1419.  
  1420.  
  1421.                  #include "litecomm.h"
  1422.                  #include "lcproto.h"
  1423.                  #include "lcpxm.h"
  1424.  
  1425.                  int lcym_recv(PROTO *pcb, char *storagepath);
  1426.  
  1427.  
  1428.             DESCRIPTION
  1429.  
  1430.  
  1431.             Receive one or more files using YModem protocol.
  1432.  
  1433.             The storagepath variable must be the path to the directory in
  1434.             which received files will be placed. It must be of the form
  1435.  
  1436.                       C:\DIR1\DIR2\
  1437.  
  1438.             The trailing '\' is significant and required.
  1439.  
  1440.             Once called, all files will be received from the send system,
  1441.             unless the transfer is canceled or aborted.
  1442.  
  1443.  
  1444.             EXAMPLE
  1445.  
  1446.  
  1447.             See QBTTL.
  1448.  
  1449.  
  1450.             RETURN VALUES
  1451.  
  1452.  
  1453.             This function returns no values.
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.  
  1466.                                          Page 23
  1467.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1468.                      LITECOMM (TM) COMMUNICATIONS TOOLBOX
  1469.                                Protocol Engines
  1470.  
  1471.  
  1472.  
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.                                    lczm_send
  1480.  
  1481.  
  1482.        SUMMARY
  1483.  
  1484.  
  1485.             #include "litecomm.h"
  1486.             #include "lcproto.h"
  1487.             #include "lczm.h"
  1488.  
  1489.             int lczm_send(PROTO *pcb, char **filelist);
  1490.  
  1491.  
  1492.        DESCRIPTION
  1493.  
  1494.  
  1495.        Send one or more files using ZModem protocol.
  1496.  
  1497.        Due to the complexities of batch transfers, the programmer must
  1498.        create a list of file names to be transferred. QBTTL shows one
  1499.        approach to building the list, though not necessarily the best
  1500.        approach. The file list must end with a zero length file name.
  1501.  
  1502.        Once called, all files will be sent to the receiving system,
  1503.        unless the transfer is canceled or aborted.
  1504.  
  1505.        MSC USERS NOTE: The files to be transferred should be either in
  1506.        the default directory, or in a directory specified in the PATH
  1507.        environment variable.
  1508.  
  1509.  
  1510.        EXAMPLE
  1511.  
  1512.  
  1513.        See QBTTL.
  1514.  
  1515.  
  1516.        RETURN VALUES
  1517.  
  1518.  
  1519.        This function returns no values.
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.                                     Page 24
  1531.             Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1532.                           LITECOMM (TM) COMMUNICATIONS TOOLBOX
  1533.                                     Protocol Engines
  1534.  
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.                                         lczm_recv
  1544.  
  1545.  
  1546.             SUMMARY
  1547.  
  1548.  
  1549.                  #include "litecomm.h"
  1550.                  #include "lcproto.h"
  1551.                  #include "lczm.h"
  1552.  
  1553.                  int lczm_recv(PROTO *pcb, char *storagepath);
  1554.  
  1555.  
  1556.             DESCRIPTION
  1557.  
  1558.  
  1559.             Receive one or more files using ZModem protocol.
  1560.  
  1561.             The storagepath variable must be the path to the directory in
  1562.             which received files will be placed. It must be of the form
  1563.  
  1564.                       C:\DIR1\DIR2\
  1565.  
  1566.             The trailing '\' is significant and required.
  1567.  
  1568.             Once called, all files will be received from the send system,
  1569.             unless the transfer is canceled or aborted.
  1570.  
  1571.  
  1572.             EXAMPLE
  1573.  
  1574.  
  1575.             See QBTTL.
  1576.  
  1577.  
  1578.             RETURN VALUES
  1579.  
  1580.  
  1581.             This function returns no values.
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.  
  1594.                                          Page 25
  1595.                  Copyright (c) 1987 - 1991 Information Technology, Ltd.
  1596.  
  1597.  
  1598.  
  1599.  
  1600.  
  1601.  
  1602.  
  1603.  
  1604.  
  1605.  
  1606.  
  1607.                                       Contents
  1608.  
  1609.  
  1610.  
  1611.                  Chapter 1  GETTING STARTED WITH PROTOCOLS             1
  1612.                     1.1  INTRODUCTION  . . . . . . . . . . . . . . . . 1
  1613.                     1.2  BASIC ENGINE INTERFACE  . . . . . . . . . . . 1
  1614.                        1.2.1  PROTOCOL INITIALIZATION  . . . . . . . . 2
  1615.                        1.2.2  DATA TRANSFER  . . . . . . . . . . . . . 3
  1616.                        1.2.3  PROTOCOL SHUTDOWN  . . . . . . . . . . . 3
  1617.  
  1618.                  Chapter 2  INITIALIZATION DETAILS                     5
  1619.                     2.1  THE MANDATORY FUNCTIONS . . . . . . . . . . . 5
  1620.                        2.1.1  LCP_ALLOC  . . . . . . . . . . . . . . . 5
  1621.                        2.1.2  LCP_SETPROTO . . . . . . . . . . . . . . 5
  1622.                     2.2  THE OPTIONAL STEPS  . . . . . . . . . . . . . 6
  1623.                        2.2.1  ABORT FUNCTION . . . . . . . . . . . . . 6
  1624.                        2.2.2  STATUS FUNCTION  . . . . . . . . . . . . 6
  1625.                        2.2.3  SIGNAL MONITORING  . . . . . . . . . . . 8
  1626.  
  1627.                  Chapter 3  FUNCTION REFERENCE                         9
  1628.                     3.1  INTRODUCTION  . . . . . . . . . . . . . . . . 9
  1629.  
  1630.                  lcp_alloc                                             9
  1631.  
  1632.                  lcp_free                                             11
  1633.  
  1634.                  lcp_setproto                                         12
  1635.  
  1636.                  lcp_setsignal                                        13
  1637.  
  1638.                  lcpxmsnd                                             14
  1639.  
  1640.                  lcpxmrec                                             16
  1641.  
  1642.                  lcpwxsnd                                             18
  1643.  
  1644.                  lcpwxrec                                             20
  1645.  
  1646.                  lcym_send                                            22
  1647.  
  1648.                  lcym_recv                                            23
  1649.  
  1650.                  lczm_send                                            24
  1651.  
  1652.                  lczm_recv                                            25
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.                                             i
  1659.  
  1660.  
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.                                       ii
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.                                        Tables
  1736.  
  1737.  
  1738.                  Table 2.1: XModem Status Codes  . . . . . . . . . . . 7
  1739.                  Table 2.2: ZModem Status Codes  . . . . . . . . . . . 7
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.                                            iii
  1787.